home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / web / fweb / fweb-1.40 / boot / ibm / pc / READ_ME.PC < prev   
Encoding:
Text File  |  1993-10-29  |  10.2 KB  |  223 lines
  1.          --- BOOTSTRAPPING FWEB ON THE IBM-PC ---
  2.                    Version 1.30
  3.                    June 17, 1993
  4.  
  5.    This file discusses issues that are specific to bootstrapping FWEB on
  6. the IBM-PC.   First of all, you may not need to anything, since executable
  7. binaries are supplied; see below.  Otherwise, you may wish to read the file
  8. INSTALL_FWEB.tex for a general overview.
  9.  
  10.  
  11. * EXECUTABLE BINARIES
  12.  
  13.    In the present release, the  executable binaries 
  14.  
  15.     ftangle.exe --- The full-blown ftangle, including Ratfor.
  16.     ftangle0.exe --- Ftangle without Ratfor.
  17.     fweave.exe --- The fweave processor.
  18.  
  19. MAY BE supplied.  If they are present, they will be found in the
  20. /pub/fweb/executables subdirectory.  If they are not present, it means that
  21. I haven't had time to produce them yet; there have been recurring problems
  22. with the IBM RISC/6000 on which I generate them.  If you need them
  23. desparately, please notify me.  
  24.  
  25. These binaries were compiled with Microsoft 6.00.  If they work, you do not
  26. need to compile the bootstrap code; proceed to the fun part of your program
  27. development.  If they do not work, please notify me.  In particular, let me
  28. know about any situation that generates a stack overflow.  These files were
  29. prepared on an IBM RISC/6000 using the pcsim program to simulate DOS.  I
  30. don't have much experience with that program, except that it's incredibly
  31. slow.
  32.  
  33. Unfortunately, these processors will NOT do themselves; the complexity of
  34. v1.21 and later requires too much space for the internal arrays.
  35.  
  36.  
  37. * ENVIRONMENT VARIABLES
  38.  
  39.    The processors look for environment variables such as ``HOME''.  If
  40. ``HOME'' is not defined on your system, say something like
  41.  
  42.     set HOME=.
  43.  
  44. NOTE that there is no white space before or after the equals sign.  (It
  45. won't work right otherwise.)  To see what environment variables are set,
  46. simply say ``set''.
  47.  
  48.  
  49. * BOOTSTRAPPING
  50.  
  51.    NOTE: The bootstrap code has been only tested so far with the Microsoft
  52. C compiler.  (It may be tested with TURBO-C++; check with me.)  If you
  53. attempt to use another compiler, you may encounter difficulties; consult
  54. with me.
  55.  
  56.    ALSO NOTE: If you have one of the original 8088 machines, with no hardware
  57. speed-up enhancements, you will likely find FWEB unusably slow for jobs of
  58. any substantial length. There's no problem with enhanced versions. Give it
  59. a try.
  60.  
  61.    (Thorsten Ohl has proposed and tested a buffering scheme that should
  62. give some improvements in run time. However, that has not yet been
  63. implemented in the master FWEB sources.)
  64.  
  65.    Several significant difficulties were encountered while attempting to
  66. make FWEB work on the IBM-PC:
  67.  
  68.     (1) memory limitations;
  69.  
  70.     (2) pointer problems;
  71.  
  72.     (3) compiler bugs.
  73.  
  74. Most likely, any gross difficulties you encounter with bootstrapping FWEB
  75. will be related to one of these three areas. That doesn't mean that you
  76. won't encounter bugs with FWEB itself, but remember that FWEB does run
  77. successfully on a variety of machines, so suspect one of the three areas above
  78. first. 
  79.  
  80. (1) MEMORY LIMITATIONS.
  81.  
  82.    FWEB is a large, sophisticated program. Therefore, when you first
  83. attempt to compile and link the bootstrap code supplied in this directory,
  84. STRIP DOWN YOUR SYSTEM AS MUCH AS YOU CAN so that maximum memory is available
  85. to the compiler. Try to make CHKDSK report about 600K of main memory
  86. available. Of course, the compiler will complain if it can't find enough
  87. memory, but I've encountered situations in which the compiler ran through
  88. to the end without complaining but produced faulty code that was corrected
  89. when the available memory was enlarged. If the Borland compiler finishes
  90. with ``Available memory 0'', don't trust the result.
  91.  
  92.    At present, FWEB should compile successfully with either the Borland
  93. Turbo C compiler or the Microsoft C compiler. (To select which compiler to
  94. use, you must either use the make file or define certain macros
  95. from the compiler's command line; see below.)  To accomplish even this
  96. much, a relatively major restructuring had to be done to reduce the size of
  97. the various object modules. Nevertheless, you may find that some other
  98. compilers choke on individual functions that are too large; for example,
  99. there are a few extremely large switch statements. You may be able to tell
  100. your compiler to increase the size of its internal tables by some sort of
  101. command-line option. If not, if there's enough demand I will eventually try
  102. to figure out how to subdivide things up further.
  103.  
  104.    A different sort of memory problem arises when you have obtained a
  105. working FWEB, but IT complains about running out of memory when working on
  106. some particularly large source code. In round numbers, FTANGLE.EXE and
  107. FWEAVE.EXE are each about 200K. That leaves you probably 300K to 400K of
  108. memory, which is enough to handle fairly sizable codes (including FTANGLE
  109. and FWEAVE themselves). However, if FWEB complains you may need to change
  110. the default allocation sizes for the various internal tables. This is done
  111. via the -y... command-line option (which can be put into FWEB.INI); see the
  112. user manual.
  113.  
  114. (2) POINTER PROBLEMS.
  115.  
  116.    FWEB allocates almost all of its memory dynamically (at run time). In
  117. particular, it can allocate blocks of memory that are longer than 64K
  118. bytes. This means that pointers must be able to point anywhere and that
  119. pointer arithmetic must be the most general possible. On the pc, pointers
  120. are 32 bits long, but they are divided into segment:offset parts, where
  121. each of segment and offset are 16 bits long. Generally by default, the
  122. compilers implement pointer arithmetic only on the offset portion; this
  123. speeds things up. It is, however, not satisfactory.  For Borland,
  124. Microsoft, and almost certainly for the other compilers as well, YOU MUST
  125. EXPLICITLY USE THE ***HUGE*** MEMORY MODEL. This not only ensures that
  126. arithmetic is done on the full 32 bit pointers, it also ensures that the
  127. pointers have unique, normalized representations so that inequalities
  128. involving pointers can be tested correctly. Although maintaining the
  129. normalized form slows things down, it seems to be a price one has to pay.
  130.  
  131.    Some compilers make a distinction between ``far'' pointers and ``huge''
  132. pointers. Both of these are 32 bits, but only the huge pointer is
  133. normalized. Peculiarly, sometimes even in the huge memory model pointers
  134. are far by default, not huge. If you want them to be huge, you have to
  135. declare them explicitly. Thus, almost all FWEB pointers had to be
  136. explicitly declared huge, a tedious and annoying exercise. It's quite
  137. conceivable that I didn't get that entirely correct, since in a few cases
  138. the pointers dare not be huge; there may be some residual bugs lurking
  139. here. If you are using some other compiler, you must make sure that the
  140. memory model and pointer declarations allow for the full range of
  141. operations on 32 bit pointers.
  142.  
  143. (3) COMPILER and other BUGS
  144.  
  145.    I've encountered compiler bugs using both the Microsoft and Borland
  146. compilers. I originally switched from Microsoft to Borland partly because
  147. an older version of Microsoft crashed when generating the huge memory model
  148. (and partly because Borland seemed to be able to handle larger functions).
  149. Microsoft 6.0 seems to work OK.
  150.  
  151.  
  152. --- COMPILING FWEB ---
  153.  
  154.    As explained in INSTALL_FWEB.tex, the compile and link information is
  155. all contained in the Unix-style make file MAKEFILE.  MAKEFILE includes a
  156. default file, DEFAULTS.MK, in order to define certain macros.
  157.  
  158. If you look into DEFAULTS.MK, you will find that the compile and
  159. link lines are defined by macros, so they can be easily changed. Note, in
  160. particular, that the macro "ibmpc" must be defined from the compiler's
  161. command line. Also note the use of compiler-command-line options to
  162. suppress or turn on various kinds of compiler warning messages. You may
  163. still get a few warnings, for example about unused variables (I'll clean
  164. this up in the future), but as long as they're warnings, not errors,
  165. they're probably harmless. If you get an error that isn't immediately
  166. apparent, check with me.  Although it is costly in terms of both space and
  167. speed, you should for awhile generate code that checks for stack overflow.
  168. This is done with the option settings as supplied.  Note also the
  169. constructions involving /Dpart=1, /Dpart=2, or /Dpart=3.  These define
  170. preprocessor 
  171. macros that are used to split FTANGLE.C and FWEAVE.C into three parts so the
  172. compiler doesn't run out of heap space.  The splitting is simply done by
  173. commenting out two-thirds of the code at a time. This seems not to be necessary
  174. with Borland with maximum memory, so you might be able disable this if you
  175. want. 
  176.  
  177.    To bootstrap with BORLAND, say
  178.  
  179.     MAKE boot
  180.  
  181. To bootstrap with MICROSOFT (I've tested with version 6.0; previous version
  182. may or may not work), say
  183.  
  184.     NMAKE boot
  185.  
  186. The bootstrap entry to the make file requires the TOUCH facility in order to
  187. ensure that the *.c and *.h files are the newest. Microsoft doesn't provide
  188. a separate TOUCH utility, but if you don't have a TOUCH of your own,
  189. instead of saying ``NMAKE boot, say
  190.  
  191.     NMAKE -t *.c *.h
  192.     NMAKE all
  193.  
  194.    If you run out of heap space during the compile, try executing the
  195. offending compile line by itself, rather than via NMAKE.  (For version
  196. 1.23, I had this problem with part 1 of fweave.)
  197.  
  198.    Once you get the bootstrap code compiled and linked successfully, you
  199. may be tempted to say ``NMAKE'' (or ``NMAKE all''), which should now
  200. recreate the *.c and *.h files by tangling the web sources. Unfortunately,
  201. you may find that the FTANGLE you have created attempts to allocate too
  202. much memory to coexist with NMAKE. You may have to run FTANGLE directly, or
  203. from a simple batch file.  [If you will only be tangling small jobs, you
  204. can reduce the amount of memory FTANGLE allocates by inserting appropriate
  205. ``-y...'' commands in the style file. (Read about memory allocation in the
  206. user manual.) However, if you wish to make FTANGLE do itself and FWEAVE,
  207. then it needs to be essentially as big as it is configured by default.]
  208.  
  209.    I make no promises to debug something that's not compiled with Borland or
  210. Microsoft, but I'll probably be able to recognize where the difficulty
  211. lies.
  212.  
  213. --- RUNNING FWEB ---
  214.  
  215.    Various test/demo files are provided to help you debug your new
  216. processors. See INSTALL_FWEB.tex for details.
  217.  
  218.    Finally, let it be noted that the IBM-PC version of FWEB hasn't been
  219. tested very thoroughly. Consider yourself a pioneer, and good luck!
  220. (Many thanks to Arnold Kritz and Thorsten Ohl, the first pioneers.)
  221.  
  222.  
  223.